Skip to main content

Get Master Products

Method: GET
/data-provider/products

As a Data Provider of iFoodDS, you can use the Get Master Products API to query master products from the iFoodDS Trace Exchange platform.

info

This endpoint is being refined and thus subject to change. These docs will update when changes are made.

Request​

Type: application/json

Retrieving master products via the API is done through paging. The request requires a series of query parameters which define the page that must be returned. These parameters must be supplied in the url when the get is executed in order to return the result set for the page being queried.

Query Parameters​

Optional​

  • page (number): The page index of the products to return. The first page is index 0.
  • size (number): The number of results to return per page. Default value is 20.
  • id (UUID, repeatable): Matches any specified DII product ID (diiId).
  • itemCode (string, repeatable): Matches any specified vendor item code (vendorItemCode). This filter does not fall back to the data-provider code.
  • alternateItemCode (string, repeatable): Matches any specified alternateItemCode value (IN match).
  • gtin (string, repeatable): Matches any specified gtin value (IN match).
  • itemUpc (string, repeatable): Matches any specified value in the stored UPC column.
  • innerPackUpc (string, repeatable): Matches any specified innerPackUpc value (IN match).
  • plu (string, repeatable): Matches any specified plu value (IN match).
  • itemDescription (string, repeatable): Matches any specified vendor item description (vendorItemDescription).
  • brandName (string, repeatable): Matches any specified brandName value (IN match).
  • productCommodity (string, repeatable): Matches any specified productCommodity value (IN match).
  • productVariety (string, repeatable): Matches any specified productVariety value (IN match).
  • ftlCategory (string, repeatable): Matches any specified ftlCategory value (IN match).
  • isFtlItem (boolean): Filters by equality on the stored ftlItem value (true or false).
  • scientificName (string, repeatable): Matches any specified scientificName value (IN match).
  • acceptableSpeciesName (string, repeatable): Matches any specified acceptableSpeciesName value (IN match).
  • isCoveredByGdst (boolean): Filters by equality on the stored gdst value (true or false).
  • submitStartDateTime (ISO local datetime): Includes only products whose dateModified is on or after the specified date and time (inclusive).
  • submitEndDateTime (ISO local datetime): Includes only products whose dateModified is on or before the specified date and time (inclusive).

Repeatable Filters​

For filters marked repeatable, supply multiple values as a comma-separated list or repeat the query parameter. For example, id=<uuid1>,<uuid2> or id=<uuid1>&id=<uuid2>. IN matching returns records matching any supplied value for that filter.

Data Constraints​

  • submitStartDateTime and submitEndDateTime use ISO local datetime values in the format yyyy-MM-ddTHH:mm:ss (for example, 2026-09-28T14:30:00).
  • Both date filters apply to dateModified, and both boundaries are inclusive.
  • Boolean filters accept true or false.

Response​

Return result for the master products queried.

{
    "content": [
        {
            "id": "<event id>",                
            "itemCode": "<item code>",
            "alternateItemCode": "<alternate item code>",
            "itemDescription": "<item description>",
            "gtin": "<gtin>",
            "itemUpc": "<item upc>",
            "innerPackUpc": "<inner pack upc>",
            "plu": "<plu>",
            "isFtlItem": <is ftl item>,
            "ftlCategory": "<ftl category>",
            "isCoveredByGdst": <is covered by gdst>,
            "brandName": "<brand name>",
            "packStyle": "<pack style>",
            "packSize": "<pack size>",
            "productCommodity": "<product commodity>",
            "productVariety": "<product variety>",
            "scientificName": "<scientific name>",
            "acceptableSpeciesName": "<acceptable species name>",
            "dataProviderVendorName": "<data provider vendor name>",
            "dataProviderVendorId": "<data provider vendor id>"
        }
    ],
    "pageable": {
        "pageNumber": <page number>,
        "pageSize": <page size>,
        "sort": {
            "unsorted": <is unsorted>,
            "sorted": <is sorted>,
            "empty": <is page empty>
        },
        "offset": <offset size>,
        "unpaged": <is unpaged>,
        "paged": <is paged>
    },
    "totalPages": <total pages>,
    "totalElements": <total elements>,
    "last": <is last page>,
    "numberOfElements": <number of elements>,
    "size": <page size>,
    "number": <page number>,
    "sort": {
        "unsorted": <is unsorted>,
        "sorted": <is sorted>,
        "empty": <is empty>
    },
    "first": <is first page>,
    "empty": <is page empty>
}

Content​

  • id (uuid): The id of the master product
  • itemCode (string): The product's item code
  • alternateItemCode (string): The product's alternate item code
  • itemDescription (string): Product Description for the item
  • gtin (string): Case-level Global Trade Identification Number (GTIN-14). GS1 GTIN Executive Summary
  • itemUpc (string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive Summary
  • innerPackUpc (string): Point of sale barcode, may be GTIN-8, GTIN-12, GTIN-13, or GTIN-14. GS1 GTIN Executive Summary
  • plu (string): Item-level Price Look-up Code. PLU Codes Search — IFPS
  • isFtlItem (boolean): Indicates whether product is on the Food Traceability List (FTL)
  • ftlCategory (string)*: Indicates the product's FTL category, i.e. “soft cheese”, “shell eggs”, “nut butter”, “cucumbers”, “herbs”, “leafy greens”, “melons”, “peppers”, “sprouts”, “tomatoes”, “tropical tree fruits”, “fresh-cut fruits”, “fresh-cut vegetables”, “finfish”, “smoked finfish”, “crustaceans”, “molluscan shellfish”, “ready-to-eat deli salads”, or “multiple-ftl-ingredients” *Required if on the FTL 
  • isCoveredByGdst (boolean): Indicate if the product is part of GDST
  • brandName (string): The brand of the product that appears on the consumer package
  • packStyle (string): Product's pack style, e.g. "Case", "Carton", "Tray", "Clamshell", etc.
  • packSize (string): Product's pack size as Packaging Configuration OR Count OR Weight + Unit of Measure, e.g. "20 x 12 oz bags"
  • productCommodity (string): For fresh produce, the description of the commodity, e.g. "Peppers"
  • productVariety (string): For fresh produce, the description of the variety, e.g. "Jalapeno"
  • scientificName (string): For seafood, the scientific name of the species, see: FDA Seafood List
  • acceptableSpeciesName (string): For seafood, a description of the common species name, see: FDA Seafood List
  • dataProviderVendorName (string): Name of the vendor/supplier
  • dataProviderVendorId (string): Your ID for the vendor/supplier

Pageable​

  • pageable (object)
    • pageNumber (number): The current page number in the page series. Index 0 is first page
    • pageSize (number): The number of events contained in the page
    • offset (number): If there is an offset specified on there return results this will be populates. Default is 0
    • unpaged (boolean): If the record set is unpaged then true else false
    • paged (boolean): If the record set is paged then true else false
    • sort (object)
      • unsorted (boolean): If the record set is unsorted then true else false
      • sorted (boolean): If the record set is sorted then true else false
      • empty (boolean): If the record set is empty then true else false
  • totalPages (number): The total amount of pages that contain all events in the query
  • totalElements (number): The total amount of events in the query
  • last (boolean): If the page is the last in the series then true else false
  • numberOfElements (number): The total amount of events in the table
  • size (number): The number of events contained in the page
  • number (number): The current page number in the page series
  • sort (object)
    • unsorted (boolean): If the record set is unsorted then true else false
    • sorted (boolean): If the record set is sorted then true else false
    • empty (boolean): If the record set is empty then true else false
  • first (boolean): If the page is the first in the series then true else false
  • empty (boolean): If the page is empty then true else false